Option Explicit

'################################################################
' Descriptor
' 对象类型数据的数组引用的接口
'################################################################

'################################################################
' Property
'################################################################
' 获取当前数组引用中已使用的长度
Public Property Get Count() As Long
End Property

' 获取当前数组引用的最大索引
Public Property Get MaxIndex() As Long
End Property

'################################################################
' Function
'################################################################
' 添加 count 个空数据到数组中
' 如果容量不足，将会自动扩容
' 空数据将会同一被设置成 Nothing
'
' @param count 需要添加的空数据数量
Public Sub AddNull(ByRef count As Long)
End Sub

' 获取指定索引下的数据
' @param index 数组索引，如果越界将会抛出异常
Public Function Item(ByRef index As Long) As Variant
End Function

' 获取指定索引下的数据
' 获取数据时，将不会检查索引的范围，如果索引越界会产生异常
' 在可以保证索引一定安全的情况下，可以通过该方法来获取数据，通过省略索引范围检查来提升效率
' @param index 数组索引，如果越界将会抛出异常
Public Function unsafeItem(ByRef index As Long) As Variant
End Function

' 设置指定索引下的数据
' @param index 数组索引，如果越界将会抛出异常
' @param val 需要保存到数组中的数据
Public Sub setVal(ByRef index As Long, ByRef val As Variant)
End Sub

' 向数组末尾添加数据，如果数组容量不足将会自动扩容
' @param val 需要保存到数组中的数据
Public Sub Add(ByRef val As Variant)
End Sub

' 从数组的开头添加数据，如果数组容量不足将会自动扩容
' @param val 需要保存到数组中的数据
Public Sub AddFirst(ByRef val As Variant)
End Sub

' 将数据 `val` 插入索引 `index` 的位置
' 支持的索引范围为 `0--IObjArrayRef.Count()`
'
' @param index 数据需要插入的索引
' @param val 需要保存到数组中的**对象类型数据**
Public Sub Insert(ByRef index As Long, ByRef val As Variant)
End Sub

' 清空数组内容
'
' @optional-param initSize 可选参数, 清空后重新初始化数组的容量
'                 小于 0 时，只会清除数组引用，不会调整数组容量
Public Sub clear(Optional ByRef initSize As Long = -1)
End Sub

' 删除指定索引下的数据
'
' 如果索引超出了数组的边界，不会抛出异常，默认不会执行任何操作
' 该操作会使数组的可用长度 - 1
'
' @param index 数组索引
Public Sub remove(ByRef index As Long)
End Sub

' 尝试从当前数组中搜索与参数 val 相同的数据，并删除
'
' 如果 needAll=False, 则只会删除第一个与 val 相同的数据
' 如果 needAll=True, 则会遍历整个数组并删除与 val 相同的所有数据
' 该操作会使数组的可用长度变小
'
' @param val, 需要删除的数据
' @optinal-param needAll 是否需要删除所有相同的数据
'                默认=False，只删除第一个和 val 相同的数据
Public Sub removeVal(ByRef val As Variant, Optional ByRef needAll As Boolean = False)
End Sub

' 删除最后一个元素
Public Sub removeLast()
End Sub

' 删除最后一个元素，并返回删除的数据
'
' @return 被删除的最后一个元素
'         如果当前数组引用中已经没有元素了，将会返回一个 `Empty`
Public Function pollLast() As Variant
End Function

' 获取数组引用中的最后一个元素
' 如果当前数组引用是空的，则返回 `Empty`
Public Function getLast() As Variant
End Function

' 合并另一个基础类型数组引用中的数据
' @param others, 另一个基础类型数组引用
Public Sub mergeArrRef(ByRef others As IObjArrayRef)
End Sub

' 生成当前数组引用的切片
' @optional-param startIdx 起始位置
' @optional-param stopIdx 终止位置(最终不会包含 stop 的索引)
' @optional-param step 步长
'                      默认值 = 1
'                      不能是 0，如果设置了 0 将会抛出异常
Public Function slice(Optional ByRef startIdx As Variant, Optional ByRef stopIdx As Variant, Optional ByRef step As Variant = 1) As IObjArrayRef
End Function

' 克隆当前数组引用对象
Public Function clone() As IObjArrayRef
End Function

' 复制索引 `[startIdx, endIdx)` 范围的内数据到新的数组引用对象中
' @optional-param startIdx 起始索引
' @optional-param endIdx 结束索引（不包括）
Public Function copyToNewArray(Optional ByRef startIdx As Long = 0, Optional ByRef endIdx As Long = -1) As IObjArrayRef
End Function

' 获取当前数组引用中，数组缓存的真实长度
Public Function unsafeRealSize() As Long
End Function